Technotes

Defining the Error

The "Not Enough External Memory (3)"error means there is not enough C heap memory for your title. Typically, this error is generated when there is not enough memory to load a media item required by a title. (For AMTPE-savvy programmers, this is the error message returned by the keyIfNULL method.) The term external memory in the error message refers to the standard C handle and pointer heap in the application environment. It is called external (just like the Apple Media Language (AML) keyword) because it is managed by the C code of the AMT runtime engine. Internal memory is the AML heap (see pg. 4-27 through 4-28 of the AMTPE User's Guide for more information).

Figure 1 Memory components of an AMT title

C stack

The C stack is an area of memory that holds temporary information used while your title is running. The C function calling chain (and some associated data) and any local variables are kept here. Its size is dependent on the particular system configuration. There is no way for either the end user or the developer to change the amount of memory allocated to the C stack.

C heap

The C heap is the standard C heap from which memory can be allocated using system calls such as NewPtr, NewHandle (under Mac OS) and GlobalAlloc (under Windows). When your title loads a media item, it allocates a block of memory from the C heap to hold that item.

Under Mac OS, the size of the C heap can be calculated by totaling the sizes of the other memory areas, and subtracting this total from the overall amount of memory allocated to the title. For example, if you allocate 5 MB to your title, and 3 MB is required for the other memory areas, then 2 MB is allocated to the C heap.

Under Windows, the size of the C heap is the amount of free memory available to Windows, minus the sizes of the other memory areas. For example, if you have 8 MB free on your Windows machine, and the other memory areas of your title use 3 MB, then 5 MB is allocated to the C heap. Because the total amount of free memory will vary, depending on the number of other Windows applications that are running when your title is launched, the size of the C heap will vary each time you run your Windows titles.

This means that you can change the size of the C heap by changing the sizes of the other memory areas. Methods to change the sizes of other memory areas are discussed later in this Technote.

AML stack

The AML stack is an area of memory that holds temporary information used while your title is running . The AML calling chain and any local variables are kept here.

For titles built with RuntimeMaker or AMTPE, the AML stack default size is 1K. For titles built with AMT, the Macintosh AML stack default size is 128K, and for a Windows title the AML stack default size is 64K.

There is usually no need to change this value for titles built with either the minimal or standard AMT engines. If there is a lot of recursion in your code, or for titles built using a custom engine, it may be helpful to increase this value.

Methods to change the size of this component are discussed later in this Technote.

AML heap

The AML heap is an area used to load any static or dynamically created objects for your title (see pages 4-26 through 4-28 of the AMTPE User's Guide for more details on static and dynamic objects). For titles built with Runtime Maker or AMTPE, the default size is 640K. For AMT 2.0 titles, a minimum value of 256K must be allocated to this component (this can be changed - see the section "How Do I Change AML Heap/Stack Memory Allocated To My Title").

This value should be increased or decreased depending on the number of objects the title is using. Because it is not easy to estimate ahead of time how much space a title will need, there are ways (discussed below) to calculate an approximate value.

The default AML heap size for the AMT application is 2048K.

AML code

Allocating Memory For Your Title

Macintosh Titles

Via the Finder

1. To allocate memory for your Macintosh title via the Finder, click on your title icon so that it's highlighted.
2. In the Finder, go to the File menu.
3. Choose Get Info menu item.
4. In the Memory Requirements dialog box that appears, enter values in the Minimum size and Preferred size fields, as shown in Figure 2.

Figure 2 The GetInfo box for Apple Media Tool title.

via a Resource Editor

• Modify the `SIZE' resource of your title using a resource editor like ResEdit. Figure 3 shows what the resource looks like when viewed with ResEdit.

Figure 3 SIZE resource

There are three 'SIZE' resources in your title, numbered -1, 0, and 1. The -1 'SIZE' resource corresponds to the Suggested size field of the Get Info dialog box, the 0 'SIZE' resource sets the Minimum size field, and the 1 'SIZE' resource sets the Preferred size field.

For each of the 'SIZE' resources you set the number of bytes allocated to that setting in the Size field (see Figure 3 above). You can also set a Min size, also in bytes. This is the minimum value that the user can set that field to using the Get Info dialog box. For example, if you set the Size field of the 0 'SIZE' resource to 5120000 and the Min size field to 2560000, then the value displayed in the Get Info dialog box's Minimum size field will be 5000K, and the smallest value the user can set this to will be 2500K.

AMTPE users can also set the default values assigned to the 'SIZE' resources for all the projects they compile. This is done by using ResEdit to alter the 'SIZE' resources in the file Title.rsrc, which is found in the Title folder within your Key folder. All subsequent projects will use these new values when they are compiled.

Note:

The memory partition you allocate to your title will be divided up among the C code/heap/stack and AML code/heap/stack areas discussed in the previous section. For example, if you allocate a 6 MB memory partition to your title, those 6 MB will be divided up internally by AMT among the various areas.

Windows Titles

General memory allocation for an application running under a Windows 3.1 or Windows 95 environment is handled differently than under Mac OS. The Windows Memory Manager parcels out memory to applications as needed from the total free memory space, not from a partition of pre-defined size. There is no need, therefore, to specify a memory partition for your title under Windows. If you request memory and the Windows Memory Manager can find it, it will return it to you. If it can't find any, an allocation error is returned.

For AMT 2.0 titles, you can specify the minimum amount of free RAM that must be available before your title will run needed at various screen bit depths by modifying the MINIMUM RAM FOR BIT DEPTH variable in the .INI file associated with your Windows title. For example, to set the minimum free RAM needed when running on an 8-bit screen to 4096K, you would include the following line in your .INI file:

MINIMUM RAM FOR BIT DEPTH 8=4096

When your Windows title starts up, it checks the screen bit-depth, then reads the .INI file to find out the minimum free RAM required for that bit-depth. If there is enough free RAM available, it starts up, and allocates fixed amounts of that memory for the AML stack and AML heaps already discussed. You can control the size of each of these areas, as described in the next section.

Here are some techniques you can use to change the AML stack and heap settings for your title.

Macintosh Titles

To modify the amount of memory allocated to the AML heap and stack areas for a Macintosh-based title, launch the title while holding down the control key.

Doing this will bring up the dialog box shown in Figure 4.

Figure 4 AML Heap/Stack settings dialog

Simply enter the desired values in the edit boxes. The values you enter will be stored in the `KSIZ' resource for the title.

Note:

The `KSIZ' resource may not exist for your title. It is created only if you alter the heap and/or stack values for your title. If you do not modify either of these settings, the default values of 640K for the heap and 1K for the stack will be used.

Note:

There is a minimum value of 256K that must be allocated to the AML heap. You can change this restriction, but it requires that you use the AMTPE environment. If you have AMTPE, alter the code for the AdjustKSIZ method in the file Application.c.

You must manually modify the `KSIZ' resource using a resource editor such as ResEdit. Figure 5 represents the `KSIZ' resource as viewed from ResEdit.

Figure 5 A sample title `KSIZ' resource

Windows Titles

You can modify the amount of memory allocated to the AML heap and stack areas for a Windows title by opening up the .INI file associated with your title and changing the HEAP and STACK program variables.

You need to remove the semicolon in front of each variable in your .INI file for these settings to take effect.

Here is what these variables look like in a typical .INI file:

[SIZE]
HEAP=640
STACK=64

You can modify the amount of memory allocated to the AML heap and stack areas by modifying the MEMORY resource that resides in your title's .EXE executable file. Here is the format of this resource (note that the actual values may be different):

0 MEMORY
BEGIN
	640,		/* WORD (KB) Key Heap Size */
	63,		/* WORD (KB) Key Stack Size */
	4096		/* WORD (KB) Needed Global Size */
END

There is no minimum 256K AML heap value for Windows titles.

AMT 2.0 titles, both Macintosh and Windows

Figure 6 Viewing free memory as your title is executing

The Free value is the amount of memory available (unused) in the C heap -- in other words, the amount of external memory available. As previously stated, all the media items for a screen are loaded into the C heap. AMT allocates memory to the C heap after memory has been allocated to all the other components of a title.What is left over is given to the C heap.

The AML Free value is the amount of memory available in the AML heap. As stated earlier, the AML heap contains all the static and dynamic objects of a title. Memory is allocated to the AML heap before any memory is given to the C heap. This means that as you increase the AML heap and/or stack size, you are actually decreasing the amount of memory available for the C heap.

The Free numbers displayed for each screen will be different depending upon whether you are viewing your title from within the AMT application or outside of it (i.e., in the Finder or in the Windows environment), since larger memory partitions are usually allocated to the AMT application than to the title itself.

When optimizing the amount of memory needed for your title, the goal is to make the above Free values as close to zero as possible. Some strategies for doing this are described in the section "Allocating Enough `External Memory' for Your Title" in this Technote.

Windows 95 Note:

Under Windows 95, holding down the shift key while double-clicking on a application's .EXE file from the desktop will cause all the files in the Windows to be opened. This can be confusing and is also likely the reduce the free memory available to your title, since it can cause several other applications to be launched along with your title. To avoid this, double-click on the .EXE file, then press the shift key, once the title has started loading.

AMT 1.2 titles, both Macintosh and Windows

Using a Windows Memory Watcher App

AML Media Object Requirements

Make sure enough C heap memory is allocated to the title (below are techniques for doing this). Once you have done this, the next step is to get the "free" amounts as close to zero as possible, so that your title can run in as little RAM as possible. The techniques for doing this are described as follows:

AMT 2.0 Titles

Here is one method for determining the minimal amount of memory for your Macintosh and Windows titles:

1. Allocate a large amount of memory to your title (e.g., 8 MB)
2. Allocate a large amount of memory to the AML heap for your title, (e.g., 2 MB).
3. Launch your title while pressing the Shift key (so you can view the available space).
4. Browse the title and look for minimum "Free" and "AML Free" numbers.
5. Subtract the minimum "AML Free" number from the number you allocated to the AML heap (that you view using the Control key trick described in the section "Changing the AML Heap & Stack Components"). If this new value is less than 256K, AMT will set it to 256K. Refer to the section "Changing AML Heap & Stack Components."
6. Set the AML heap to this new value.
7. Subtract the minimum "Free" number from the total memory partition you have allocated (i.e., the number from the "Get Info" window or 'SIZE' resource for your title).
8. Set the title's total memory partition to this new value.

AMT 1.2 Titles

There is no facility for viewing the amount of free C heap (and AML heap) memory for each screen of a running AMT 1.2 title. (You can, however, get an estimate of the amount of C heap and AML heap memory necessary for your media using techniques described in the previous section). Instead, you will have to determine this value through trial and error. The technique for doing this is identical to what was described for AMT 2.0 titles.

Note the point at which you start getting memory errors. Backing up to the last allocated memory size before you got errors will enable you to determine your title's minimal memory requirements.

Note:

If you get the "Not Enough Internal Memory (2)" error, you have not allocated enough AML heap memory.

Building Large Projects

If your larger projects fail to build using Runtime Maker, you should try increasing its available heap memory. To do this, double-click the Runtime Maker icon, while holding down the control key. This brings up the dialog box shown in Figure 4 above. You can then increase the heap size to allow Runtime Maker to build your project.

You can permanently increase the size of Runtime Maker's heap size by adjusting its 'KSIZ' resource using ResEdit.

AMTPE users may also find that the compile process can hang because insufficient heap has been allocated to the key compiler. If a large project fails to build, use ResEdit to open the file key, which is found in the Tools folder within your Key folder. This is the AML compiler, and it contains a 'KSIZ' resource. Increase the heap size, and restart MPW before trying to recompile your project.

Further Reference